Using JAMSEL

Congratulations! Now that you have installed JAMSEL and/or integrated with your project, you are now ready to start reaping the benefits of JAMSEL. The rest of this document will be a guided tour through the basic operation of Selector's build system.

First, make sure that your CLASSPATH is set up correctly. JAMSEL requires that the JAKARTA ORO jar be in your CLASSPATH. In addition, if you use the TIBCO/Rendezvous helper classes from the library, then the appropriate TIBCO jars should be in the CLASSPATH. Finally, if you use the JMS helper classes from the library, then the appropriate JMS jars should be in the CLASSPATH as well.

Next, take a look at the sample below that shows how to integrate JAMSEL with an application. A selector is created as follows:

		
			String s = "...";
			ISelector selector = Selector.getInstance(s);
      
	

Once a selector instance has been created it may be evaluated multiple times. The framework provides two options for evaluating selectors. Under the first option, the application queries the selector instance for all identifiers that were encountered during the parse. The application then creates a Map , and populates it with the values of the identifiers. Once the values of the identifiers have been set, the selector can be evaluated. The code shown below implements these steps. Note, the method getValue() is application code that fetches the value of the specified identifier:

		
			// Create the identifier value Map and fill with values
			Map identVals = new HashMap();
			for (Iterator iter = selector.getIdentifiers().keySet().iterator(); iter.hasNext(); )
			{
				String key = (String)iter.next();
				identVals.put(key, getValue(key));
			}

			// Evaluate the selector
			boolean result = selector.eval(identVals);
      
	

The second option for evaluating a selector is to use the framework's value provider strategy. The idea here is that instead of creating a Map of identifier values, the application registers a callback with the selector. The selector invokes the callback when and if it needs the value of an identifier. The framework provides build-in value provider implementations for JMS and TIBCO/Rendezvous. In addition, the application can implementation its own value providers by simply implementing the IValueProvider interface.

The code shown below implements these steps for JMS. Note, the eval() method takes a correlation Object parameter. The correlation parameter is passed as-is to the value provider implementation:

		
			// Get the JMS message and create value provider
			Message jmsMsg = ...;
			IValueProvider vp = com.codestreet.selector.jms.ValueProvider.valueOf(jmsMsg);

			// Get any application correlation data
			Object corr = ...;

			// Evaluate selector
			Result result = selector.eval(cp, corr);
      
	

Of the two options shown above, the value provider approach can result in better performance. For example, suppose the selector expression contains many sub-expressions and a total of 10 identifiers. The Map approach will require the application to set the value of all 10 identifiers on each evaluation. In contrast, in case some evaluations result is short-circuting of the selector expression, the value provider approach will not examine all 10 identifiers. Use the approach that best fits your specific needs.

A note on thread safety. The selector implementation is immutable. In other words, a selector instance can be used concurrently by multiple threads without any internal or external synchronization.

That concludes the tour of JAMSEL. For more details please see the whitepapers.